
/**
 *  \file GA_api.h
 *
 *  \brief This file defines the Generic Audio Core Application Interface - includes
 *  Data Structures and Methods.
 */

/*
 *  Copyright (C) 2020. Mindtree Ltd.
 *  All rights reserved.
 */

#ifndef _H_GA_API_
#define _H_GA_API_


/* --------------------------------------------- Header File Inclusion */
#include "GA_bearer_api.h"

/* TODO: Place these in configuration */
#define GA_MAX_SEP                  2
#define GA_MAX_CONTEXTS             1
#define GA_MAX_STREAM_CONTEXTS      2
#define GA_MAX_CCS                  1
#define GA_MAX_ASE_CONTEXT          1
#define GA_MAX_CCID_LIST_SIZE       1
#define GA_CODEC_IE_LEN             20
#define GA_METADATA_LEN             20


/* Move to right place */
#define GA_MAX_VCP_VCS_ENTITIES                     0x01
#define GA_MAX_VCP_VOCS_ENTITIES                    0x01
#define GA_MAX_VCP_AICS_ENTITIES                    0x01

/* No. of Service Instances */
#define GA_MAX_VCS_ENTITIES                         0x01
#define GA_MAX_VOCS_ENTITIES                        0x01
#define GA_MAX_AICS_ENTITIES                        0x01

#define GA_MAX_VOCS_CHAR_AUDIO_OUTPUT_DESC_LEN      64
#define GA_MAX_AICS_CHAR_AUDIO_INPUT_DESC_LEN       64

/* Feature Flags */
#define GA_VCP_CONTROLLER
#define GA_VCP_RENDERER

#define GA_CCP_CLIENT
#define GA_CCP_SERVER

/* --------------------------------------------- Global Definitions */

/**
 * \defgroup ga_module GA (Generic Audio Layer)
 * \{
 *  This section describes the interfaces & APIs offered by the EtherMind
 *  Generic Audio (GA) module to the Application and other upper
 *  layers of the stack.
 */

/**
 * \defgroup ga_defines Defines
 * \{
 * Describes defines for the module.
 */

/**
 * \defgroup ga_constants Constants
 * \{
 * Describes Constants defined by the module.
 */

/** GA Audio Roles */
#define GA_ROLE_SINK                0x01
#define GA_ROLE_SOURCE              0x02

/** GA Capabilities */
#define GA_CAP_TYPE_CODECS          0x01
#define GA_CAP_TYPE_LOCATIONS       0x02
#define GA_CAP_TYPE_CONTEXTS        0x03

/** GA Audio Coding types */
#define GA_AUDIO_CODING_LC3         0x01
#define GA_AUDIO_CODING_INVALID     0xFF

/** LC3 specific LTV Tag defines */
#define GA_LC3CAP_SSF_TAG           0x01
#define GA_LC3CAP_SFD_TAG           0x02
#define GA_LC3CAP_ACC_TAG           0x03
#define GA_LC3CAP_SOCF_TAG          0x04

#define GA_LC3_SF_TAG               0x01
#define GA_LC3_FD_TAG               0x02
#define GA_LC3_ACA_TAG              0x03
#define GA_LC3_OCF_TAG              0x04

/** Content LTV Tag defines */
#define GA_CTX_PREFERRED_TAG        0x01
#define GA_CTX_STREAMING_TAG        0x02
#define GA_CCID_LIST_TAG            0x03 /* TODO */

/** \} */

/**
 *  \defgroup ga_events Events
 *  \{
 *  This section lists the Synchronous/Asynchronous Events notified
 *  to Application by the Module.
 */

/** GA profile events */
#define GA_SETUP_CNF                0x01
#define GA_GET_CAPABILITIES_CNF     0x02
#define GA_SEP_DISCOVER_CNF         0x03
#define GA_SEP_CONFIGURE_CNF        0x04
#define GA_SEP_SETUP_CNF            0x05
#define GA_SEP_START_CNF            0x06
#define GA_SEP_SUSPEND_CNF          0x07
#define GA_SEP_UPDATE_CNF           0x08
#define GA_SEP_RELEASE_CNF          0x09
#define GA_SEP_STATUS_IND           0x0A
#define GA_SEP_CONFIGURE_IND        0x0B
#define GA_SEP_SETUP_IND            0x0C
#define GA_SEP_START_IND            0x0D
#define GA_SEP_SUSPEND_IND          0x0E
#define GA_SEP_UPDATE_IND           0x0F
#define GA_SEP_RELEASE_IND          0x10

#define GA_EVENT_INVALID            0xFF

/** \} */

/**
 *  \defgroup ga_response Respnse Codes
 *  \{
 *  This section lists the response and reason codes for use
 *  by the module.
 */

/** GA SEP Response codes */
#define GA_SEP_RSP_SUCCESS                      0x00
#define GA_SEP_RSP_UNSUPP_OPCODE                0x01
#define GA_SEP_RSP_TRUNCATED_OPERATION          0x02
#define GA_SEP_RSP_INVALID_ASEID                0x03
#define GA_SEP_RSP_INVALID_ASE_SM_TRANSITION    0x04
#define GA_SEP_RSP_UNSUPP_AUDIO_CAPABILITIES    0x05
#define GA_SEP_RSP_UNSUPP_CONFIG_PARAM_VAL      0x06
#define GA_SEP_RSP_REJECTED_CONFIG_PARAM_VAL    0x07
#define GA_SEP_RSP_INVALID_CONFIG_PARAM_VAL     0x08
#define GA_SEP_RSP_UNSUPP_METADATA              0x09
#define GA_SEP_RSP_REJECTED_METADATA            0x0A
#define GA_SEP_RSP_INVALID_METADATA             0x0B
#define GA_SEP_RSP_INSUFFICIENT_RESOURCES       0x0C
#define GA_SEP_RSP_UNSPECIFIED_ERROR            0x0D

/** GA SEP Error Reasons */
#define GA_SEP_RSN_DIRECTION                    0x01
#define GA_SEP_RSN_CODEC_ID                     0x02
#define GA_SEP_RSN_CODEC_SPECIFIC_CONFIG_LEN    0x03
#define GA_SEP_RSN_CODEC_SPECIFIC_CONFIG        0x04
#define GA_SEP_RSN_SDU_INTERVAL                 0x05
#define GA_SEP_RSN_FRAMING                      0x06
#define GA_SEP_RSN_PHY                          0x07
#define GA_SEP_RSN_MAX_SDU_SIZE                 0x08
#define GA_SEP_RSN_RETRANSMISSION_NUMBER        0x09
#define GA_SEP_RSN_MAX_TRANSPORT_LATENCY        0x0A
#define GA_SEP_RSN_PRESENTATION_DELAY           0x0B
#define GA_SEP_RSN_METADATA_LENGTH              0x0C

/** \} */

/** \} */

/* --------------------------------------------- Data types /Structures */

/**
 *  \defgroup ga_structures Data Structures
 *  \{
 *  This section lists the various data structures for use
 *  by the module.
 */

/** GA Context Reference for an Endpoint */
typedef UINT8 GA_CONTEXT;

/** GA Endpoint device */
typedef GA_BRR_DEVICE GA_ENDPOINT;

/** GA LC3 Codec Capability */
typedef struct _GA_LC3_CODEC_CAP
{
    /** Sampling Frequencies Supported */
    UINT16 supported_sf;

    /** Frame Durations Supported */
    UINT8 supported_fd;

    /** Audio Channel Counts */
    UINT16 acc;

    /** Octets per Codec Frame Supported */
    UINT32 supported_opcf;

} GA_LC3_CODEC_CAP;

/** GA LC3 Codec Configuration */
typedef struct _GA_LC3_CODEC_CONF
{
    /** Sampling Frequency */
    UINT8 sf;

    /** Frame Duration */
    UINT8 fd;

    /** Audio Channel Allocation */
    UINT32 aca;

    /** Octets per Codec Frame */
    UINT16 opcf;

} GA_LC3_CODEC_CONF;

/** Codec Information */
typedef struct _GA_CODEC_INFO
{
    /** Coding type */
    UINT8 coding;

    /** Company ID */
    UINT16 company_id;

    /** Cendor Codec ID */
    UINT16 vendor_id;

    /** Codec Capabilities/Configuration Information Element */
    UCHAR ie[GA_CODEC_IE_LEN];

    /** Codec Information element length */
    UCHAR ie_len;

} GA_CODEC_INFO;

/** GA Channel Reference */
typedef struct _GA_CHANNEL
{
    /** CIG Identifier */
    UINT8 cig_id;

    /** CIS Identifier */
    UINT8 cis_id;

} GA_CHANNEL;

/** GA Metadata */
typedef struct _GA_METADATA
{
    /** Metadata byte stream */
    UCHAR data[GA_METADATA_LEN];

    /** Metadata length */
    UINT8 length;

} GA_METADATA;

/** GA Supported Audio Capability */
typedef struct _GA_AUDIO_CAP
{
    /** Codec Information */
    GA_CODEC_INFO codec;

    /** Audio Locations */
    UINT32 locations;

    /** Preferred Context Types for the capability */
    UINT16 contexts;

} GA_AUDIO_CAP;

/** GA Codec Configuration */
typedef struct _GA_CODEC_CONFIG
{
    /** Codec ID */
    UINT8 id;

    /** Codec Configuration */
    void * conf;

} GA_CODEC_CONFIG;

/** GA QOS Capability */
typedef struct _GA_QOS_CAP
{
    /** SDU Interval Range Preference */
    UINT32 pref_sdu_interval_min;
    UINT32 pref_sdu_interval_max;

    /** Framing Preference */
    UINT8 pref_framing;

    /** PHY Preference */
    UINT8 pref_phy;

    /** MAX SDU Preference */
    UINT16 pref_max_sdu;

    /** Retransmission Number Preference */
    UINT8 pref_retxn;

    /** Max Transport Latency Preference */
    UINT16 pref_max_transport_latency;

    /** Minumum and maximum Presentation Delay supported */
    UINT32 supp_presentation_delay_min;
    UINT32 supp_presentation_delay_max;

} GA_QOS_CAP;

/** GA QOS Configuration */
typedef struct _GA_QOS_CONF
{
    /** Channel Information */
    GA_CHANNEL channel;

    /** SDU Interval */
    UINT32 sdu_interval;

    /** Framing */
    UINT8 framing;

    /** PHY */
    UINT8 phy;

    /** MAX SDU */
    UINT16 max_sdu;

    /** Retransmission Number */
    UINT8 retxn;

    /** Max Transport Latency */
    UINT16 max_transport_latency;

    /** Presentation Delay */
    UINT32 presentation_delay;

} GA_QOS_CONF;

/** GA Content Information */
typedef struct _GA_CONTENT_INFO
{
    /** Contexts for the content */
    UINT16 contexts;

    /** List of CCIDs */
    UINT8 * ccid;

    /** Number of CCIDs */
    UINT8 num_ccid;

} GA_CONTENT_INFO;

/** Stream End point Configuration */
typedef struct _GA_SEP_CONF
{
    /** Role */
    UINT8 role;

    /** Codec Capability */
    GA_CODEC_INFO codec;

} GA_SEP_CONF;

/** GA Endpoint Capability used for response */
typedef struct _GA_CAP_ENDPOINT
{
    /** Peer role under consideration */
    UINT8 role;

    /** Capability type */
    UINT8 type;

    /** Capability data */
    UCHAR * data;

    /** Capability data length */
    UINT16 datalen;

} GA_CAP_ENDPOINT;

/** ASE Information */
typedef struct _GA_ASE_INFO
{
    /** ASE Index */
    UINT8 sep_id;

    /** ASE Info data */
    UCHAR * data;

    /** ASE Infor datalen */
    UINT16 datalen;

} GA_ASE_INFO;

/** SEP Callback Information */
typedef struct _GA_SEP_INFO
{
    /** SEP Id */
    UINT8 sep_id;

    /** Event specific information */
    void * info;

} GA_SEP_INFO;

/** \} */

/**
 *  \defgroup ga_cb Application Callback
 *  \{
 *  This Section Describes the module Notification Callback interface offered
 *  to the application
 */

/** GA Profile Callback */
typedef GA_RESULT (* GA_PROFILE_CB)
                  (
                      GA_CONTEXT * ga_ctx,
                      UINT8 ga_event,
                      UINT16 ga_status,
                      void * ga_data,
                      UINT16 ga_datalen
                  );

/** \} */

/* --------------------------------------------- Macros */

/* --------------------------------------------- APIs */

/**
 * \defgroup ga_api_defs API Definitions
 * \{
 * This section describes the EtherMind Generic Audio Layer APIs.
 */

#ifdef __cplusplus
extern "C" {
#endif

/**
 *  \brief Initialize the Generic Audio (GA) layer.
 *
 *  \par Description
 *  This routine initializes the GA layer and registers and application callback.
 *
 *  \param [in] cb Application callback inteface to be registered with GA layer to handle
 *  synchronous and asynchronous events to procedures.
 *
 *  \return API_SUCCESS or an error code indicating reason for failure
 */
GA_RESULT GA_init
          (
              /* IN */ GA_PROFILE_CB cb
          );

/**
 *  \brief Register the GA capabilities.
 *
 *  \par Description
 *  This routine registers the audio capabilities of the application profile
 *  residing over the GA layer.
 *
 *  \param [in] role \ref GA_ROLE_SOURCE or \ref GA_ROLE_SINK role for this capability
 *  \param [in] audio_cap Reference to \ref GA_AUDIO_CAP data giving the audio capability for this role
 *  \param [in] audio_contexts Supported Audio contexts for this role
 *
 *  \return API_SUCCESS or an error code indicating reason for failure
 */
GA_RESULT GA_register
          (
              /* IN */ UINT8 role,
              /* IN */ GA_AUDIO_CAP * audio_cap,
              /* IN */ UINT16 audio_contexts
          );

/**
 *  \brief Register GA Streaming Endpoint.
 *
 *  \par Description
 *  This routine registers a GA streaming endpoint for a given SEP configuration
 *  and QOS capability.
 *
 *  \param [in] sep_conf Role and Codec configuration for the SEP
 *  \param [in] qos_cap Preferred QOS capability for the SEP
 *  \param [out] sep_id Endpoint identifier for future reference on successful registration
 *
 *  \return API_SUCCESS or an error code indicating reason for failure
 */
GA_RESULT GA_register_audio_sep
          (
              /* IN */ GA_SEP_CONF * sep_conf,
              /* IN */ GA_QOS_CAP * qos_cap,
              /* OUT */ UINT8 * sep_id
          );

/**
 *  \brief Register a GA content control service.
 *
 *  \par Description
 *  This routine registers a supported content control service to the GA layer and
 *  obtains a unique identifier CCID.
 *
 *  \param [in] ccs_uuid UUID of the Content Control Service registered
 *  \param [out] ccid Content Control Identifier allocated for the service
 *
 *  \return API_SUCCESS or an error code indicating reason for failure
 */
GA_RESULT GA_register_content_service
          (
              /* IN */ UINT16 ccs_uuid,
              /* OUT */ UINT8 * ccid
          );

/**
 *  \brief Setup a GA context for a peer endpoint.
 *
 *  \par Description
 *  This routine allocates a GA context for a peer endpoint, discovers the audio roles
 *  supported at the peer endpoint.
 *
 *  \param [in] device Peer Endpoint address
 *  \param [out] context Allocated GA context for the peer endpoint
 *
 *  \return API_SUCCESS or an error code indicating reason for failure
 *
 *  \note This procedure returns the \ref GA_SETUP_CNF event
 */
GA_RESULT GA_setup
          (
              /* IN */ GA_ENDPOINT * device,
              /* OUT */ GA_CONTEXT * context
          );

/**
 *  \brief Release the given GA context.
 *
 *  \par Description
 *  This routine frees up the given context of the GA layer.
 *
 *  \param [in] context Context to be freed
 *
 *  \return API_SUCCESS or an error code indicating reason for failure
 */
GA_RESULT GA_release
          (
              /* IN */ GA_CONTEXT * context
          );

/**
 *  \brief Get the capabilities of a GA endpoint.
 *
 *  \par Description
 *  This routine gets the capabilities for a GA endpoint that is setup.
 *
 *  \param [in] context Context of the peer endpoint that is setup
 *  \param [in] role Role on the endpoint for which the capabilities is required
 *
 *  \return API_SUCCESS or an error code indicating reason for failure
 *
 *  \note This procedure returns the \ref GA_GET_CAPABILITIES_CNF event
 */
GA_RESULT GA_get_capabilities
          (
              /* IN */ GA_CONTEXT * context,
              /* IN */ UINT8 role
          );

/**
 *  \brief Discover the Audio Stream Endpoints (ASE) of a GA endpoint.
 *
 *  \par Description
 *  This routine discovers the available audio stream endpoints on a GA endpoint
 *  that is setup previously.
 *
 *  \param [in] context Context of the peer endpoint that is setup
 *
 *  \return API_SUCCESS or an error code indicating reason for failure
 *
 *  \note This procedure returns the \ref GA_SEP_DISCOVER_CNF event
 */
GA_RESULT GA_sep_discover
          (
              /* IN */ GA_CONTEXT * context
          );

/**
 *  \brief Configure a given set of ASEs of a GA endpoint.
 *
 *  \par Description
 *  This routine configures the given set of one or more ASE IDs of the
 *  GA Endpoint with the requested Codec Configuration.
 *
 *  \param [in] context Context of the peer endpoint that is setup
 *  \param [in] sep_count Number of Endpoints included
 *  \param [in] sep_id List of ASE IDs
 *  \param [in] sep_role List of roles for every endpoint included
 *  \param [in] sep_codec List of Codec Configurations for every endpoint included
 *
 *  \return API_SUCCESS or an error code indicating reason for failure
 *
 *  \note This procedure returns the \ref GA_SEP_CONFIGURE_CNF event
 */
GA_RESULT GA_sep_configure
          (
              /* IN */ GA_CONTEXT * context,
              /* IN */ UINT8 sep_count,
              /* IN */ UINT8 * sep_id,
              /* IN */ UINT8 * sep_role,
              /* IN */ GA_CODEC_INFO * sep_codec
          );

/**
 *  \brief Setup a given set of ASEs of a GA endpoint.
 *
 *  \par Description
 *  This routine sets up the QOS configuration on the given set of one or
 *  more ASE IDs of the GA Endpoint.
 *
 *  \param [in] context Context of the peer endpoint that is setup
 *  \param [in] sep_count Number of Endpoints included
 *  \param [in] sep_id List of ASE IDs
 *  \param [in] sep_qos List of QOS Configurations for every endpoint included
 *
 *  \return API_SUCCESS or an error code indicating reason for failure
 *
 *  \note This procedure returns the \ref GA_SEP_SETUP_CNF event
 */
GA_RESULT GA_sep_setup
          (
              /* IN */ GA_CONTEXT * context,
              /* IN */ UINT8 sep_count,
              /* IN */ UINT8 * sep_id,
              /* IN */ GA_QOS_CONF * sep_qos
          );

/**
 *  \brief Start a given set of ASEs of a GA endpoint.
 *
 *  \par Description
 *  This routine enables the given set of one or more ASE IDs of
 *  the GA Endpoint.
 *
 *  \param [in] context Context of the peer endpoint that is setup
 *  \param [in] sep_count Number of Endpoints included
 *  \param [in] sep_id List of ASE IDs
 *  \param [in] sep_content List of Content Control information for
 *  every endpoint included
 *
 *  \return API_SUCCESS or an error code indicating reason for failure
 *
 *  \note This procedure returns the \ref GA_SEP_START_CNF event
 */
GA_RESULT GA_sep_start
          (
              /* IN */ GA_CONTEXT * context,
              /* IN */ UINT8 sep_count,
              /* IN */ UINT8 * sep_id,
              /* IN */ GA_CONTENT_INFO * sep_content
          );

/**
 *  \brief Update a given set of ASEs of a GA endpoint.
 *
 *  \par Description
 *  This routine updates the given set of one or more ASE IDs of
 *  the GA Endpoint with new set of Content Control Information.
 *
 *  \param [in] context Context of the peer endpoint that is setup
 *  \param [in] sep_count Number of Endpoints included
 *  \param [in] sep_id List of ASE IDs
 *  \param [in] sep_content List of Content Control information for
 *  every endpoint included
 *
 *  \return API_SUCCESS or an error code indicating reason for failure
 *
 *  \note This procedure returns the \ref GA_SEP_UPDATE_CNF event
 */
GA_RESULT GA_sep_update
          (
              /* IN */ GA_CONTEXT * context,
              /* IN */ UINT8 sep_count,
              /* IN */ UINT8 * sep_id,
              /* IN */ GA_CONTENT_INFO * sep_content
          );

/**
 *  \brief Suspend a given set of ASEs of a GA endpoint.
 *
 *  \par Description
 *  This routine disables the given set of one or more ASE IDs of
 *  the GA Endpoint.
 *
 *  \param [in] context Context of the peer endpoint that is setup
 *  \param [in] sep_count Number of Endpoints included
 *  \param [in] sep_id List of ASE IDs
 *
 *  \return API_SUCCESS or an error code indicating reason for failure
 *
 *  \note This procedure returns the \ref GA_SEP_SUSPEND_CNF event
 */
GA_RESULT GA_sep_suspend
          (
              /* IN */ GA_CONTEXT * context,
              /* IN */ UINT8 sep_count,
              /* IN */ UINT8 * sep_id
          );

/**
 *  \brief Release a given set of ASEs of a GA endpoint.
 *
 *  \par Description
 *  This routine releases the given set of one or more ASE IDs of
 *  the GA Endpoint.
 *
 *  \param [in] context Context of the peer endpoint that is setup
 *  \param [in] sep_count Number of Endpoints included
 *  \param [in] sep_id List of ASE IDs
 *
 *  \return API_SUCCESS or an error code indicating reason for failure
 *
 *  \note This procedure returns the \ref GA_SEP_RELEASE_CNF event
 */
GA_RESULT GA_sep_release
          (
              /* IN */ GA_CONTEXT * context,
              /* IN */ UINT8 sep_count,
              /* IN */ UINT8 * sep_id
          );

/**
 *  \brief Notify SEP state updates to an Endpoint.
 *
 *  \par Description
 *  This routine notifies updates in all SEP states to the endpoint specified.
 *  To notify to all connected endpoints, the parameter is given NULL.
 *
 *  \param [in] device Endpoint to be notified. NULL if all connected endpoints
 *  to be notified.
 *
 *  \return API_SUCCESS or an error code indicating reason for failure
 */
GA_RESULT GA_sep_notiy_updates
          (
              /* IN */ GA_ENDPOINT * device
          );

#ifdef __cplusplus
};
#endif

/** \} */

/** \} */

#endif /* _H_GA_API_ */

